# core_engine_types.py
# -*- coding: utf-8 -*-

"""
核心引擎使用的数据结构类型定义

使用 TypedDict 来增强代码的可读性和类型检查。
"""

from typing import Dict, Any, List, Tuple, Set, Optional, TypedDict
from datasketch import MinHash

# --- 基本信息片段定义 ---
class FragmentInfo(TypedDict):
    """表示文本中的一个片段及其位置信息"""
    text: Optional[str]    # 片段的文本内容 (可能为 None 如果提取失败)
    start_char: int        # 片段在原文中的起始字符索引 (包含)
    end_char: int          # 片段在原文中的结束字符索引 (不包含)
    length: int            # 片段的实际字符长度

# --- 命中详情定义 ---
class HitDetail(TypedDict):
    """表示一次具体的相似性命中详情"""
    hit_id: str            # 本次命中的唯一 ID (例如 "LIT_001", "SEM_001")
    source_file: str       # 命中的来源语料库文件名 (仅包含文件名，不含路径)
    match_type: str        # 匹配类型 ("literal" 或 "semantic")
    similarity_score: float # 相似度得分 (字面匹配为 1.0，语义匹配为计算值)
    input_fragment: FragmentInfo    # 命中的输入文档片段信息
    source_fragment: FragmentInfo   # 命中的来源文档片段信息

# --- 任务信息定义 ---
class TaskInfo(TypedDict):
    """存储关于本次查重任务的基本信息"""
    task_id: str           # 检测任务的唯一编号
    check_time: str        # 检测完成时间 (格式: "YYYY-MM-DD HH:MM:SS")
    original_filename: str # 待检测文件的原始名称
    processing_time_seconds: float # 处理本次任务的总耗时 (秒)

# --- 文本统计信息定义 ---
class TextStats(TypedDict):
    """存储输入文档和比对过程相关的统计数据"""
    total_words: int       # 输入文档的总词数 (基于分词结果)
    total_chars: int       # 输入文档的总字符数 (基于清理后文本)
    total_paragraphs: int  # 输入文档的有效段落数量
    corpus_doc_count: int  # 比对库中的文档总数量
    compared_doc_count: int # 本次任务实际进行详细比对的语料库文档数量 (候选集大小)

# --- 聚合指标定义 ---
class AggregateMetrics(TypedDict):
    """存储计算得到的各种聚合性相似度指标"""
    # === 字面匹配相关指标 ===
    overall_similarity_ratio: float             # 总文字复制比 (%)
    duplicate_chars_count: int                  # 重复字数 (字面匹配覆盖的唯一字符数)
    max_similarity_ratio_single_source: float   # 单篇最大文字复制比 (%)
    max_duplicate_chars_single_source: int      # 单篇最大重复字数
    max_similarity_source_name: str             # 单篇最大重复字数的来源文件名
    literal_hit_source_count: int               # 字面匹配命中的来源文档数量
    suspected_paragraph_count: int              # 包含字面重复内容的段落数量 (基于映射)
    max_duplicate_chars_in_paragraph: int       # 单个段落内最大字面重复字数
    min_duplicate_chars_in_paragraph: int       # 单个段落内最小字面重复字数 (若存在则 > 0)
    front_part_overlap_chars: int               # 前部 N 字符内的重复字数 (N 来自配置)
    rear_part_overlap_chars: int                # 后部 N 字符内的重复字数 (N 来自配置)

    # === MinHash 相关指标 (若启用) ===
    max_minhash_jaccard: float                  # 最高 MinHash Jaccard 相似度估值
    max_minhash_source_name: str                # MinHash 最高相似度来源文件名

    # === N-gram 相关指标 (若启用) ===
    max_ngram_score: float                      # 最高 N-gram TF-IDF 余弦相似度
    max_ngram_source_name: str                  # N-gram 最高相似度来源文件名
    high_ngram_source_count_threshold_0_7: int  # N-gram 相似度 > 0.7 的来源文档数量

    # === 语义匹配相关指标 (若启用) ===
    semantic_hit_block_count: int               # 语义相似块的总数量 (所有来源合计)
    semantic_involved_input_block_count: int    # 至少存在一个语义相似匹配的输入文本块的数量
    max_semantic_score: float                   # 所有语义匹配中的最高相似度得分
    max_semantic_source_name: str               # 最高语义相似度得分所在的来源文件名

# --- 预处理后的文档数据结构 ---
class ProcessedDocData(TypedDict):
    """存储单个文档经过预处理后的完整数据"""
    source_file_path: str                   # 文档的原始文件路径
    source_file_mtime: float                # 文档的最后修改时间戳 (用于缓存验证)
    config_snapshot: Dict[str, Any]         # 处理该文档时使用的关键配置项快照 (用于缓存验证)
    cleaned_text: str                       # 清理和规范化后的文本内容
    paragraphs_pos: List[Tuple[str, int, int]] # 段落列表 [(段落文本, 起始位置, 结束位置), ...]
    sentences_pos: List[Tuple[str, int, int]]  # 句子列表 [(句子文本, 起始位置, 结束位置), ...]
    stats: Dict[str, int]                   # 文本统计信息 {'total_words', 'total_paragraphs', 'total_chars'}

    # --- 可选的预计算字段 (用于优化，可能不在缓存中持久化) ---
    minhash_signature: Optional[MinHash] = None # 预计算的 MinHash 签名 (如果启用)
    chunk_embeddings: Optional[Any] = None      # 预计算的文本块嵌入向量 (例如 numpy array 或 torch tensor)
    chunk_type_used_for_embedding: Optional[str] = None # 计算嵌入时使用的块类型 ('sentence' 或 'paragraph')

# --- 核心查重结果数据结构 ---
class CoreResultData(TypedDict):
    """封装一次查重任务的完整结果"""
    task_info: TaskInfo                         # 任务基本信息
    text_stats: TextStats                       # 文本统计信息
    aggregate_metrics: AggregateMetrics         # 聚合相似度指标
    hit_details_by_source: Dict[str, List[HitDetail]] # 按来源文件名组织的命中详情列表
    error_message: Optional[str]                # 如果处理过程中发生错误，记录错误信息 (中文)
